PATH Mac OS X Server Documentation > Mac OS X Server Release Notes

Mac OS X Server Developer Release Notes:
Creating and Installing Packages

This release note describes what a package is and what you must do to create one. It also gives the procedure to follow in the Developer Release to install packages by hand. In Customer Release 1,you will be able to use the Installer application to install and uninstall packages.

What is a Package?

A package is a structured collection of files used for installing a software product such as an application, a framework, a set of frameworks or applications,documentation, and clip art. Packages are optimized for the Installer application, which can both install and uninstall software using the information contained in in a package. Specifically, a package is a file package--that is a directory that presents itself opaquely in the File Viewer, like a file. The files a package contains are of two types. First there is the entity to be installed, which is a compressed archive file in tar format. All other files exist to expedite the installation (and uninstallation) processes. Some ot these files are created after the software is installed.

Most files in a package take the same name (usually that of the installed product), but have different extensions. They are:

product.tar.gz: The software product as archived by the gnutar tool and compressed by the gzip tool.
product.bom: Bill of materials: a binary record of the where the files and directories of the product are to be installed (or are installed). Used in verification and in uninstallation.
product.info: An ASCII file containing, in key/value form, the strings to appear in the user interface of the Installer application. It also contains information used in installing the product, such as the preferred installed location in the file system. It can also contain comments.
product.sizes: Contains the number of files installed, the combined size of all installed files, and the size of those files when compressed. These values are computed by the package tool.
product.tiff: The tiff icon to be displayed in the Installer application when this package is installed or uninstalled.
product.status: Contains a string indicating the installed status of the product, usually "installed" or "compressed." This file is created during installation.
prodiuct.location: The root directory where the product is installed. The user can specify where this is, overriding the default installation root directory. This file is created after the product is installed, and is used in uninstallation.

Creating a Package

To create a package you need to do three or four things:

Create a directory structure mirroring the installed locations of product files and copy those files to their proper locations in this structure. Also set file and directory permissions appropriately, including ownership and groups. The parent directory of this directory structure is known as the "root directory."
Obtain a TIFF icon for your package (optional).
Create a .info file for your package.
Run the package tool, located in /usr/bin.

The TIFF icon will be displayed in the Installer application when that becomes available. The following discussion focuses on the third and fourth tasks.

The .info File

You must create an ASCII file that has an extension of ".info" and a name that will be adopted as the product name, for example, MyApp.info results in a packaged named MyApp.pkg. Each line of the .info file consists of a key value on the left and, after some whitespace (spaces or tabs), the value associated with that key.

Key	Value
Title	The title of the package. This is displayed in the Installer user interface.
Version	The version the package, as a string. This is displayed in the Installer user interface.
Description	A short description of the contents of the package and any caveats or important information, such as compatible operating-system versions or dependencies. This is displayed in the Installer user interface.
DefaultLocation	The directory in the file system where to install the package; the installer.sh script allows users to change the default installed location, unless Relocatable is set to NO.
Relocatable	If YES, allows users to change the default installed location.
Diskname	If the package is put on a disk, the label of the disk (put "#%d" after the label to order it sequentially, in case of multiple disks).
NeedsAuthorization	YES means must be installed as root
Application	YES if package is an application, NO otherwise
DeleteWarning	A message displayed when the package is uninstalled. The user is given a chance to cancel the operation. The message is displayed followed by this question: "Are you sure you want to delete packagename?"
InstallOnly	YES if the only valid operation is installing, NO if uninstalling is also allowed.
DisableStop	YES if aborting installation of the package is not allowed, NO otherwise

Example from DeveloperLibs.pkg:

# These fields will be displayed in the Info View
Title Developer   Software Libraries
Version           Rhapsody Developer Release 2
Description       This package contains software libraries 
you need to develop software using Apple Rhapsody. Install it 
only on computers running Rhapsody Developer Release 2. Install 
this package after you install the Developer Tools package.
 # These fields are used for the installed and floppy locations
DefaultLocation         /
Relocatable             NO
Diskname DeveloperLibs  #%d
 # Other fields
NeedsAuthorization      YES
Application             NO
InstallOnly             YES
DisableStop             NO

Run the package Tool

You run the package tool (located in /usr/bin) to create packages. This tool has this usage syntax:

    package [-f] root-dir info-file [tiff-file] [-d dest-dir]

As you can see, the only items required are the root directory (root-dir) and the .info file. The root directory holds a directory structure that lays down the product the way it is supposed to be installed. for example, if you had an application that also depends upon a special framework, your root directory might contain something like this:

    /System/Applications/MyProduct.app/...
    /System/Library/Frameworks/MyProduct.framework/...

The root directory and the .info file can be an absolute path (for example, "/tmp/MyPackage/System/Application/MyApp.app") or a path relative to where you execute the package command. The optional parameters of this command are:

-f: The root directory's parent directory is treated as ".". When -f isn't specified, the root directory itself is treated as ".".
tiff-file: A file with a ".tiff" extension containing a TIFF icon representing the product. This icon is displayed in the Installer user interface.
-d dest-dir: A directory to which the package should be written. It can be an absolute or relative path. The destination directory is by default the directory in which the package command is executed.

Here is an example of the package command:

   # package Software/Gizmo Gizmo.info Gizmo.tiff -d /Local/User/jsmith/Packages

Installing a Package

In Developer Release 2 of Rhapsody, user the installer.sh script (in /usr/bin) to install and uninstall packages. You should install packages as root, especially if you want to write a receipt of the package to /System/Library/Receipts (necessary for uninstallation).

The installer.sh script has the following minimum syntax when used for installing packages:

    installer.sh package.pkg [install_directory]

Note that if you do not specify an installation directory, the package will be installed in the default installation location, as specified in the .info file. Also, if the Relocatable flag is NO in the .info file, you can only install the package in the default location.

To uninstall a package, the minimum installer.sh syntax is:

    installer.sh --delete package.pkg

The installer.sh script offers additional options for installation and uninstallation, and also prints out package information, including the list of a package's bill of materials. Use the --help option to find out about these options.